Data streams v2 by 1egoman · Pull Request #1985 · livekit/client-sdk-js

1egoman · 2026-06-23T20:57:53Z

Warning

This change relies on some new SFU updates to be able to function. Checkout main (really, livekit/livekit@86a79f8 or later), build + run the SFU locally, and point any test app at this local SFU for testing.

Overview

Data streams v2 consists of some updates to data streams to add three things:

Single packet data streams for short (< 15kb), finite length payloads
DEFLATE compression, when both the sender and all receivers support compression/decompression
A maximum 15kb size for data stream attributes to close this as a DOS vector

This pull request contains the initial web implementation and initial data streams spec which will be used to propagate this across all other client sdks.

Performance

Both 1 and 2 together at least doubles ⚠️ data stream throughput across the spectrum of network conenctions and payload sizes.

Before:

After:

Using sendText means that future optimizations to send a single data stream packet can be enabled.

…chanism

…a streams

…ream

…t / split into 15k MTU Doing this makes data arrive a bit faster since it's not waiting for compressed bytes to accumulate before sending out a "fully filled" packet

streams

Tag each data stream chunk with a "compression index" which if > 0 points to a given DecompressionStream which should be used for preprocessing received bytes.

…s whole data stream fflate allows flushing the compressed bytes midway through so that they can be emitted "together" as a chunk in the output stream, which a DecompressionStream('deflate-raw') can properly consume.

…nStream for single packet sends So now fflate is only used in the multi packet data stream case, and could be more easily broken out into its own concrete dependency block.

…ally make much of a difference for agent transcriptions And I don't think it would be too hard to re-introduce in the future as an opt in setting, either with fflate, or if compressionstream gets an explicit "flush" option

…n code

…rt it

…fields

changeset-bot · 2026-06-23T20:57:57Z

⚠️ No Changeset found

Latest commit: d77161f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

1egoman · 2026-06-23T20:59:28Z

NOTE: The diff is quite large, and a big reason why it is is because I have both this example app AND the spec checked in. I'll remove these before an eventual merge which will make the diff a lot more reasonable.

Feel free to ignore this examples/data-stream-benchmark directory when reviewing.

1egoman · 2026-06-23T21:02:04Z

+/** The data-streams-v2 wire signals carried directly on the header: the compression flag and the
+ * inline single-packet payload. Both used to live in reserved header attributes; they are now
+ * first-class protobuf fields on `DataStream.Header`. */
+export interface StreamHeaderV2Fields {
+  /** Compression applied to the inline/chunked payload. Defaults to `NONE` when omitted. */
+  compression?: DataStream_CompressionType;
+  /** The full payload smuggled into the header for single-packet (inline) sends. */
+  inlineContent?: Uint8Array;
+}


Note to self: get rid of this and inline these two fields directly into the relevant function calls. Or name this something more generic if I decide to keep it.

1egoman · 2026-06-23T21:08:38Z

+      mimeType: 'text/plain',
+      timestamp: Date.now(),
+      topic: options?.topic ?? '',
+      size: totalTextLength, // NOTE: size is always the pre-compression byte length


question: I'm not 100% sure this is the right call, making the data stream header size always the uncompressed byte length. This means effectively that the value could be larger than the literal compressed bytes sent, which is a little weird.

The reason why I decided to do it is it is impossible to determine the compressed byte length ahead of time before compressing all the data. So if this were the compressed length, you'd have to receive all file chunks, compress each one, then buffer all in memory before you could finish the stream and determine the full length, which obviously isn't going to work.

1egoman · 2026-06-23T21:10:29Z

+      // set text part of progress to 1
+      handleProgress(1, 0);


Note to self: add some tests for the onProgress stuff. I'm not sure I've fully exercised it to make sure I didn't break anything here. Though worth noting I did find some bugs where in some paths onProgress wasn't being called before so I'm actually not convinced it was working properly before either.

1egoman · 2026-06-23T21:12:38Z

+    // Incremental text streams are never compressed (CompressionStream does not support flushing
+    // mid-stream); one-shot compression lives in sendText.
+    //
+    // Note that a future streamText could send a context-takeover style deflate-raw stream with
+    // intermedia explicit `Z_SYNC_FLUSH`s - receivers already will handle this properly today.


Note to reviewers - this is an important callout. The Outgoing- half of this change doesn't support compression for streamed data streams (only sendText / sendFile) but the infrastructure exists for this on the Incoming- half so this could be added in the future in a fully backwards compatible way without needing a new clientProtocol bump.

1egoman · 2026-06-23T21:13:07Z

+    // FIXME: make this a global event to ensure "max listener" warning won't get logged for lots of
+    // in flight data streams.
    engine.once(EngineEvent.Closing, onEngineClose);


Note to self: fix this pre-existing bug as part of this larger change, I think right now there will me a "max listener" warning if you try to send too many data streams concurrently.

1egoman · 2026-06-23T21:14:37Z

+    // Phase 1: Try to send as a single packet data stream
+    //
+    // This is not being done explictly for files, because it's challenging to determine ahead of
+    // time how well the file contents will compress (and whether the total output will be under the
+    // MTU). Revisit this in the future though.


Important callout for reviewers - sendFile has some special behavior (it doesn't do single packet data streams) because it's difficult / impossible to determine if the whole file will fit into a single packet without buffering in memory aggressively.

1egoman · 2026-06-23T21:16:20Z

+export async function deflateRawDecompress(data: Uint8Array): Promise<Uint8Array> {
+  const ds = new DecompressionStream('deflate-raw');
+  const writer = ds.writable.getWriter();
+  writer.write(data as NonSharedUint8Array);
+  writer.close();
+  return collect(ds.readable);
+}


Note to reviewers: I opted to use deflate-raw instead of deflate or gzip because deflate-raw is the most compact representation and the extra metadata that deflate includes (checksum and ordering) is superfluous in a SCTP delivered reliable data channel context.

1egoman · 2026-06-23T21:17:51Z

Note to reviewers: here is the (mostly complete) spec for this feature.

1egoman added 30 commits June 4, 2026 12:58

refactor: rename constant

c049e4c

fix: make rpc use datastream.sendText, NOT streamText

4df4fbd

Using sendText means that future optimizations to send a single data stream packet can be enabled.

fix: convert rpc tests from streamText -> sendText

fea1f2c

feat: add initial support for single packet data streams via hacky me…

b7f9d00

…chanism

feat: add backwards compatibility back in for old multi packet v1 dat…

15c4a1a

…a streams

feat: check all participants in room before broadcasting a v2 data st…

9811524

…ream

feat: add initial data stream benchmark app

54971eb

feat: add missing constants file

69bd59e

feat: add initial data stream compression implementation

2f80a8a

feat: migrate compression to get rid of "pump" and compress per packe…

f1fa99b

…t / split into 15k MTU Doing this makes data arrive a bit faster since it's not waiting for compressed bytes to accumulate before sending out a "fully filled" packet

fix: swap else if -> switch/case

3ec5e6e

feat: add initial take at streaming through CompressionStream for data

4fb1efd

streams

feat: commit hand written data streams compression approach

b1e0794

Tag each data stream chunk with a "compression index" which if > 0 points to a given DecompressionStream which should be used for preprocessing received bytes.

refactor: move to deflate-raw for all compression, move to Compressio…

8eb8ac4

…nStream for single packet sends So now fflate is only used in the multi packet data stream case, and could be more easily broken out into its own concrete dependency block.

fix: get rid of singleWrite mode on streamText

a2f0ede

fix: clean up code

5a79e3a

feat: add compression into bytestreams too

d93f017

refactor: move around outgoing data stream single packet / compressio…

7a708a5

…n code

fix: reduce needless diff churn

e285f4b

feat: add max header size breaking change

ee9dde7

feat: advertise new CAP_COMPRESSION_DEFLATE_RAW capability to SFU

8f0720b

feat: add proper OutgoingDataStreamManager tests

8378001

feat: add initial IncomingDataStreamManager tests

8858e3d

fix: ensure that compression only used when remote participants suppo…

7af75f5

…rt it

fix: fiz zlib Z_SYNC_FLUSH test

2317d5d

feat: add a few more IncomingDataStreamManager tests

80225e7

fix: reformat code

a1de874

fix: remove unused import

ec979e0

1egoman added 5 commits June 17, 2026 09:59

fix: remove Z_SYNC_FLUSH test, it was not really testing the right thing

715c55d

fix: add participant disconnect test

6d5b6e7

fix: add sendFile v1 outgoing data stream manager tests

88cbff3

feat: port over data streams implementation to use newly added proto …

86b0369

…fields

feat: commit initial data streams spec

4b904eb

1egoman requested review from lukasIO and xianshijing-lk as code owners June 23, 2026 20:57

github-advanced-security AI found potential problems Jun 23, 2026

View reviewed changes

Comment thread examples/data-stream-benchmark/api.ts Dismissed

fix: remove unused tests

d77161f

1egoman commented Jun 23, 2026

View reviewed changes

1egoman requested a review from ladvoc June 23, 2026 21:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Data streams v2#1985

Data streams v2#1985
1egoman wants to merge 36 commits into
mainfrom
data-streams-v2

1egoman commented Jun 23, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jun 23, 2026 •

edited

Loading

Uh oh!

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

1egoman Jun 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

1egoman commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Performance

Uh oh!

changeset-bot Bot commented Jun 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

1egoman commented Jun 23, 2026 •

edited

Loading

changeset-bot Bot commented Jun 23, 2026 •

edited

Loading